Building Search Script Suite documentation

Background:
The basic element of this script is JTD_buildingSearch.sqf (and a function upon which it relies, JTD_arrayShuffle.sqf). The fundamental goal of that script is to have a single AI group search all the building positions in a single enterable building, in a way that appears 'lifelike.'

Built upon that script are various 'wrappers' that allow for a greater range of AI activity. This activity includes:
- an eventhandler that sends a nearby enemy group to a building near the shooter
- a script that sends a single group, systematically, into buildings around a central point
- a script that sends an array of groups to search an array of buildings
- the basic building search script that started this whole thing

Usage:
JTD_buildingSearch.sqf (requires JTD_arrayShuffle.sqf in the same folder)
Parameters:
group = group (or unit) - the group which will conduct the search (required)
search Radius = number - radius around which to generate an array of buildings (default is 50m) (optional)
"NEAREST"/"RANDOM" = string - specifies whether to use the building nearest to the passed position or a random one (default is random) (optional)
initial position = position array (or object) - around which to search (default is leader's position at script execution) (optional)
include leader = boolean - 'true' includes the leader in the search (default is false, but if group has 2 or less, default is true) (optional)
occupy building = boolean - where 'true' means that the group will stay in the building positions when the script ends (default is false) (optional)

This script can be used as a function, in which case it returns 'true' if it completes, or 'false' if it has to exit due to some error. Check the rpt for errors.

JTD_searchFiredEH.sqf
This eventhandler can be assigned to units. Upon firing, there is a random chance that nearby enemy units will be tasked to search a building near the shooter. If the group is already tasked with a building search, it will exit that iteration of the script. It will wait approximately 1 minute between checks, so fully automatic fire will not repeatedly trigger the eventhandler.

JTD_blockSearch.sqf
Parameters (all required):
group = group (or unit) - the group which will search all the buildings in an area
start position = position array (or object) - the position upon which to search
search radius = number - the radius within which to find enterable buildings

This script builds on the basic building search script by taking a single group and ordering it to sequentially search enterable buildings within a specified radius.

JTD_arraySearch.sqf (requires JTD_searchersOccupied.sqf in the same folder)
Parameters (all required):
group array = array of groups - the groups that will be assigned
building array = array of buildings - the buildings that will be searched

This script takes the groups in the passed array and assigns them to buildings from the other array. If there are more groups than buildings, random groups from the passed array will be assigned. If there are more buildings than groups, the buildings will be searched sequentially, re-using groups as they become available.

Global variables:
JTD_lockedSearchGroups - [array] as groups are assigned to buildings, they are added to this global variable, as they finish the search, they are removed. That array can be checked to determine whether to assign new waypoints to a group. (Created and monitored by JTD_buildingSearch.sqf.)

JTD_searchAvailables - [array] from the array search script, as groups are removed from the locked search groups, they are added to this array. (Created within JTD_arraySearch.sqf, and JTD_searchersOccupied.)

JTD_bldgsrchPath - [string] can be set in a unit init or the init.sqf, it allows mission makers to put these scripts in a different folder than the mission root folder. Just assign the path in the variable, and it will be prepended to the script execution commands.

JTD_searchDebug - [boolean] this will spam your rpt with all sorts of information that may or may not be useful to you. Needs to be set in init line of unit or init.sqf. 

ooooooooooooooooooooooooooooooooooooooooooooooooooo
Credits:
OFPEC
Rommel for CBA function searchNearby
Tophe for random house patrol

Testers/Feedback:
MadRussian
GvsE
Kremator
Manzilla
============================
JTD:
-- DMarkwick
-- ReconPathFinder
-- TRexian